1   package org.infinispan.container;
2   
3   import org.infinispan.metadata.Metadata;
4   import org.infinispan.container.entries.CacheEntry;
5   import org.infinispan.container.entries.InternalCacheEntry;
6   import org.infinispan.container.entries.InternalCacheValue;
7   import org.infinispan.container.versioning.EntryVersion;
8   import org.infinispan.factories.scopes.Scope;
9   import org.infinispan.factories.scopes.Scopes;
10  
11  /**
12   * A factory for {@link InternalCacheEntry} and {@link InternalCacheValue} instances.
13   *
14   * @author Manik Surtani
15   * @since 5.1
16   */
17  @Scope(Scopes.NAMED_CACHE)
18  public interface InternalEntryFactory {
19  
20     /**
21      * Creates a new {@link InternalCacheEntry} instance based on the key, value, version and timestamp/lifespan
22      * information reflected in the {@link CacheEntry} instance passed in.
23      * @param cacheEntry cache entry to copy
24      * @param <K> The key type for the entry
25      * @param <V> The value type for the entry
26      * @return a new InternalCacheEntry
27      */
28     <K, V> InternalCacheEntry<K, V> create(CacheEntry<K, V> cacheEntry);
29  
30     /**
31      * Creates a new {@link InternalCacheEntry} instance based on the version and timestamp/lifespan
32      * information reflected in the {@link CacheEntry} instance passed in.  Key and value are both passed in 
33      * explicitly.
34      * @param key key to use
35      * @param value value to use
36      * @param cacheEntry cache entry to retrieve version and timestamp/lifespan information from
37      * @param <K> The key type for the entry
38      * @param <V> The value type for the entry
39      * @return a new InternalCacheEntry
40      */
41     <K, V> InternalCacheEntry<K, V> create(K key, V value, InternalCacheEntry<?, ?> cacheEntry);
42  
43     /**
44      * Creates a new {@link InternalCacheEntry} instance
45      * @param key key to use
46      * @param value value to use           
47      * @param metadata metadata for entry
48      * @param <K> The key type for the entry
49      * @param <V> The value type for the entry
50      * @return a new InternalCacheEntry
51      */
52     <K, V> InternalCacheEntry<K, V> create(K key, V value, Metadata metadata);
53  
54     /**
55      * Creates a new {@link InternalCacheEntry} instance
56      * @param key key to use
57      * @param value value to use
58      * @param metadata metadata for entry
59      * @param lifespan lifespan to use
60      * @param maxIdle maxIdle to use
61      * @param <K> The key type for the entry
62      * @param <V> The value type for the entry
63      * @return a new InternalCacheEntry
64      */
65     <K, V> InternalCacheEntry<K, V> create(K key, V value, Metadata metadata, long lifespan, long maxIdle);
66  
67     /**
68      * Creates a new {@link InternalCacheEntry} instance
69      * @param key key to use
70      * @param value value to use
71      * @param metadata metadata for entry
72      * @param created creation timestamp to use
73      * @param lifespan lifespan to use
74      * @param lastUsed lastUsed timestamp to use
75      * @param maxIdle maxIdle to use
76      * @param <K> The key type for the entry
77      * @param <V> The value type for the entry
78      * @return a new InternalCacheEntry
79      */
80     <K, V> InternalCacheEntry<K, V> create(K key, V value, Metadata metadata, long created, long lifespan, long lastUsed, long maxIdle);
81  
82     /**
83      * Creates a new {@link InternalCacheEntry} instance
84      * @param key key to use
85      * @param value value to use
86      * @param version version to use
87      * @param created creation timestamp to use
88      * @param lifespan lifespan to use
89      * @param lastUsed lastUsed timestamp to use
90      * @param maxIdle maxIdle to use
91      * @param <K> The key type for the entry
92      * @param <V> The value type for the entry
93      * @return a new InternalCacheEntry
94      */
95     // To be deprecated, once metadata object can be retrieved remotely...
96     <K, V> InternalCacheEntry<K, V> create(K key, V value, EntryVersion version, long created, long lifespan, long lastUsed, long maxIdle);
97  
98     /**
99      * TODO: Adjust javadoc
100     *
101     * Updates an existing {@link InternalCacheEntry} with new metadata.  This may result in a new
102     * {@link InternalCacheEntry} instance being created, as a different {@link InternalCacheEntry} implementation
103     * may be more appropriate to suit the new metadata values.  As such, one should consider the {@link InternalCacheEntry}
104     * passed in as a parameter as passed by value and not by reference.
105     * 
106     * @param cacheEntry original internal cache entry
107     * @param metadata new metadata
108     * @param <K> The key type for the entry
109     * @param <V> The value type for the entry
110     * @return a new InternalCacheEntry instance
111     */
112    <K, V> InternalCacheEntry<K, V> update(InternalCacheEntry<K, V> cacheEntry, Metadata metadata);
113 
114    /**
115     * Similar to {@link #update(org.infinispan.container.entries.InternalCacheEntry, org.infinispan.metadata.Metadata)}
116     * but it also updates the {@link org.infinispan.container.entries.InternalCacheEntry} value.
117     * <p/>
118     * If the same internal cache entry is returned and if it is a mortal cache entry, the returned instance needs to be
119     * reincarnated.
120     *
121     * @param cacheEntry original internal cache entry
122     * @param value      new value
123     * @param metadata   new metadata
124     * @param <K> The key type for the entry
125     * @param <V> The value type for the entry
126     * @return a new InternalCacheEntry instance or the existing original
127     */
128    <K, V> InternalCacheEntry<K, V> update(InternalCacheEntry<K, V> cacheEntry, V value, Metadata metadata);
129 
130    /**
131     * Creates an {@link InternalCacheValue} based on the {@link InternalCacheEntry} passed in.
132     * 
133     * @param cacheEntry to use to generate a {@link InternalCacheValue}
134     * @param <V> The value type
135     * @return an {@link InternalCacheValue}
136     */
137    <V> InternalCacheValue<V> createValue(CacheEntry<?, V> cacheEntry);
138 
139    /**
140     * Creates a copy of this cache entry and synchronizes serializes the copy process with the {@link #update(org.infinispan.container.entries.InternalCacheEntry, org.infinispan.metadata.Metadata)}.
141     * This is requires so that readers of the entry will get an consistent snapshot of the value red.
142     * @param <K> The key type for the entry
143     * @param <V> The value type for the entry
144     */
145    <K, V> CacheEntry<K, V> copy(CacheEntry<K, V> cacheEntry);
146 
147    /**
148     * Creates a L1 entry.
149     *
150     * @param <K> The key type for the entry
151     * @param <V> The value type for the entry
152     * @param key
153     *@param value @return a new {@link org.infinispan.container.entries.InternalCacheEntry}
154     */
155    <K, V> InternalCacheEntry<K, V> createL1(K key, V value, Metadata metadata);
156 }